Turnbull China Bikeride/Turnbull China Bikeride - Disc 1.iso/HENSA/MISC/SHELL.ARC/Shell/!Help

Text File | 1994-12-06 | 14KB | 374 lines

              Shell C library 1.13 06 Dec 1994
              --------------------------------


________________________________________________________________________





About Shell
-----------


Shell is a set of C routines which allow you to easily make
multi-tasking RISC OS programs which can display complicated items like
arrays, bar-graphs, blocks of text etc in windows. It uses the routines
in the DeskLib C lbrary. I wrote the Shell library to enable easy
development of neural-network simulation programs for my PhD, so it is
probably of most use to people wanting to display large amounts of data
in windows. It also provides lots of example code for writing wimp
applications.

Most of the routines are not optimised for speed, but for ease of use -
for instance, there are routines which print text in a window using
workarea coordinates, so that window-redrawing routines can work
exclusively in workarea coordinates. There are similar routines (some
macros) for drawing lines/circles/rectangles etc.

The header files are fairly well commented, and the example program
ShellEG should provide a clear idear of what Shell routines can do, and
how to use them.


________________________________________________________________________






How Shell works:
----------------

When you use Shell, you open one or more Shell-windows. The redrawing of
these windows is done entirely by the Shell library using DeskLib's
Event_ library - you don't have to worry about redraw rectangles etc.

Each Shell window can have any number of rectangle inside it. Each
rectangle has a C structure assciated with it, which contains all the
information needed to redraw the rectangle, i.e. a pointer to a
redrawing function, and various other data like the rectangle's
dimensions. Some simple rectangle redrawing functions are already part
of Shell, to draw a 2D array of text, a bar graph, or a block of text.

When a redrawing function is called, it can work in coords relative to
the rectangle, not the window workarea coords or the screen's coords; to
do this, use the supplied strucure Shell_convertpoint 'convert', which
actually represents the screen coords of the bottom-left of the
rectangle. To plot things, use Shell_Plot( plotcode, x, y, convert), or
Shell_Circle( x, y, r, convert) etc. These are macros which will use
'convert' to find the screen coors. See some of the supplied redraw
functions for examples of using these, e.g. sources.c.BarGraph,
sources.c.TextRect or sources.c.Label.

You can add a rectangle to a window with Shell_AddRectangle, supplying a
function which Shell will call when this rectangle needs redrawing. If,
instead, you just want a standard rectangle type, call Shell_Add2DArray,
Shell_AddBarGraph, Shell_AddTextRect or Shell_AddGeneralArray etc. Many
of these higher-level rectangles still require a simple function from
you; e.g. Shell_AddGeneralArray needs a function which, given an x and
y, returns a string to display at location (x,y) in the rectangle.

The TextRect functions allow you to print to a rectangle using the same
syntax as 'printf'. Thus you can have large amounts of text in a block
inside a window providing the functionality of running a program in a
taskwindow, but also allowing the use of the more graphical displays
such as arrays and bar-graphs.

You can also force rectangles/arrays etc. to be redrawn, for instance if
their contents have changed.

You can still open windows independantly of Shell if you wish - Shell
uses DeskLib's Event_Poll function, so any such window should be redrawn
etc using Event_ handlers. Also, if you register a handler for
event_REDRAW, you can do your own redrawing inside Shell windows.

You can use Shell_ to help debug a Wimp application, as long as the
application uses DeskLib's Event_ library. For example, you can output
diagnostic information to a window using Shell_Printf( ...) from within
your code. You shouldn't do this in the middle of redrawing code, for
example, as this will confuse the Wimp. There is now a function
Shell_WaitPrintf( ...) which you can use for this purpose. It is very
useful if you want to find out why your redrawing is not working.


I wrote Shell for use with programs which are basically mathematical
models, that take hours to run, which I wanted to run in the background.
i.e. they aren't conventional event-driven Wimp application. Because of
this, I've written a very simple front-end to Event_Poll called
Shell_Poll which repeatedly calls Event_Poll until an event_NULL is
received. To make a program multi-tasking, just sprinkle a few
Shell_Poll's through a program. Thus by calling Shell_Poll frequently in
your program, the system multitasks nicely, but your program gets time
when there are event_NULL's available. There is also a macro
Shell_PollSlow which calls Shell_Poll only if sufficient time has
elapsed since the last call to Shell_Poll. This time interval is set
with Shell_SetPollInterval. Using small values will result in a smooth
desktop, while larger values will result in fewer calls to Wimp_Poll
giving a jerky desktop but a faster program.

You don't have to use Shell_Poll - if your application is a conventional
event-driven one, you should just call Event_Poll directly.


You can also set the frequency with which rects are updated so that you
can tell Shell that a rect's contents have changed very frequently, but
Shell won't call Wimp_ForceRedraw each time. This speeds up your program
significantly as it means it's not continually readrawing a window.

Many rectangles can be saved in the desktop by Shift-Menu clicking on
them. e.g. you can save the times-table in the example program as text.

One very useful feature is a PlainRect. This is displayed as just a
blank rectangle inside a window, but when you save it, it saves its
contents as a sprite, allowing you to extract bar graphs/blockrects etc
directly without grabbing bits of the screen with !Paint.



________________________________________________________________________


Problems
--------


Shell has quite a few rough edges - for e.g. the maximum nuber of
windows is #defined as 4, which is ample for my programs but might not
be enough for everyone. The windows are stored in an array, but they
should really be a linked list (like the rectangles in each window,
which use DeskLib's LinkList functions).

Other things which aren't perfect are:

FontLabel.c    the font handle is not updated when a mode-change
        occurs, and the colours don't work very well in
        256-colour modes.

BarGraph.c    No facility for negative-height bars.

TextRect.c    The text is not formated - you need to put '\n' in
        occasionaly if you want the text to be multiline. This
        is not too bad as printf behaves in the same way.

PlainRect.c    This saves an area of a Shell window as a sprite by
        redirecting to a sprite, and forcing a redraw of the
        area. Text is half-size (in square pixel modes) and the
        outlines of Shell rectangles (which are created with
        Wimp_PlotIcon) don't show up for some reason.

SpriteRect.c    Doesn't detect mode changes, and so spriterects don't
        work properly if you change mode.

No facilities are provided for deleting rectangles and free-ing the
memory they took up.

And some more which I've forgotton about.


NB If anyone can fix the problems with sprites and fonts when the screen
mode is changed, it would be very useful. I don't tend to change mode
very often so haven't really the inclination to fix these problems
myself...



One thing which might make the source files difficult to read for users
of !Edit is the profusion of Tabs. The solution is to use the excellent
freeware !Zap text editor - you won't want to use !Edit again after
seeing !Zap. For users of other text editors, the tabs in Zap tab to 8
spaces so any other value will result in strange non-aligned text. I
also have my display width set to 98 characters for C code, which is
slightly too big for a mode 31 screen, but allows one extra tab for each
line.

Any application which uses Shell has to have a window called
'ShellWindow' in its template file - Shell_OpenWindow assumes this name.


One of the main uses of Shell is to show how to cope with redrawing
windows in the Wimp enviroment - I found this quite difficult to start
with. Hopefully, the Shell sources will help people understand how the
Wimp redrawing system works.


_________________________________________________________________________


Installation.
-------------

You should simply move the whole Shell library directory into your C
path. Don't move any headers into an existing .h. directory. Shell has
many header files, some of which might be the same name as ones you
already have; thus Shell source files have lines like:

#include "Shell.Array.h"

which should also be used by any of your code which uses Shell.

e.g.., if <C$Path> = ADFS:4.$.CLibs., ...other.libraries...

then you should put the entire Shell directory in ADFS:4.$.CLibs to get
a tree that looks like:

ADFS:4.$.CLibs.
               h.
                 header1      /* your existing headers */
                 header2
                 ...

               o.
                 RISC_OSLib   /* your existing libraries */
                 ...

               Shell.
                     h.
                       Shell
                       Array
                       ...

                     o.ShellLib

                     Sources.
                             c.
                               Array
                               Label
                               ...

                             MakeFile

                             o.
                               Array
                               Label
                               ...


You should link with C:Shell.o.ShellLib, or C:Shell.o.ShellEC if you use
EasyC (EasyC's library format is different from Acorn's, so
Shell.o.ShellEC contains exactly the same object files as
Shell.o.ShellLib, except that they have been made into the one library
file using EasyC's library-making tool rather than Acorn's LibFile).


An alternative to this is to run the obey file !Boot in the Shell
directory before you start to use Shell, which sets <ShellLib$Path> and
change all #include lines to #include "ShellLib:Array.h", while linking
with 'ShellLib:o.ShellLib'. This approach is similar to that used by
DeskLib. Bear in mind that I don't do this so it hasn't really been
checked.

If you use FilerPatch (by Jens Ovesen), the Shell directory will
actually behave like an application 'cos one of its access bits is set,
and be displayed with a Shell sprite, and the !Boot file will be run
automatically.



___________________________________________________________________________


Things to do
------------


What would be really nice would be to have a command-line input, so that
commands could be typed in and read by a function like Shell_scanf, with
other functions such as Shell_getc etc. You could have input from
different input rectangles, so Shell_scanf( Shell_rectblock *rectblock,
"%i", &x). There could also be a general input rectangle attatched to
the general output textrect, which would be read by Shell_scanf( NULL,
...). This would make Shell_ completely implement a standard textual
input/output system like taskwindows, but with easy to use graphics
facilities as well.

Simple x-y graphs. I've got code to do this but it's a bit messy at the
mo.

Add a saver for blockrects to save as a sprite - Done that now.

Add a saver for bargraphs.

Have a rect which displays a sprite from a spritefile - I have a messy
version of this which isn't in a fit state to be included.

At the moment, rectangles have colours and can have an icon-style
border. The default routines add various borders automatically, using
Shell_MakeRectIcon. An alternative way of doing this would be to put a
set of icons in the 'ShellWindow' in the Templates file, called 'Array',
'RectBlock' ... etc, so that any RectBlocks would have icon
charateristics (such as colours, border) from the templates file.

Add facilities to delete rectangles, freeing allocated space etc. I've
never actually needed to do this, but these functions should really be
included in the library.


___________________________________________________________________________


The Save102 sub-library
-----------------------

This library is the latest version 1.02 of the Save sublibrary from
DeskLib (with all function names prefixed by 'Shell_') . The reason it
is included here is that Shell was changed ages ago to use Save 1.02,
but the current version of DeskLib (2.10) uses Save 1.00, which doesn't
work with Shell.

When a newer version of DeskLib is released, I'll release a new Shell
without the Save102 library, which will use the DeskLib Save functions.


___________________________________________________________________________


Other things
------------

Shell is freeware and © Julian Smith. Feel free to distribute it, but
please distribute the original, not altered copies. You are not allowed
to charge more than the disc (or other medium) price for distributing
Shell.

Thanks to Alan Fitch for the shell sprites and !Run and !Obey files in
the Shell directory. These enable things like #include
"ShellLib:SpriteRect.h" as in DeskLib, if you double click one of them.

Thanks also to Ian MacDougall for making the EasyC version of the
library.


If you write any routines for extra rectangle types (e.g. to draw a
sprite in a window, or a drawfile in a window), please send them to me
so they can be included in the next release.

If you have any queries/suggestions/good ideas/extra routines/complaints
relating to Shell, I'd like to hear from you.  Feel free to contact me
at the address below:


Julian Smith


------------------------
[e-mail]
------------------------

or:

------------------------
Department of Psychology
University of Edinburgh
7 George Square
Edinburgh
EH8 9JZ
UK
------------------------